ATSUGetFontInstance

OSStatus ATSUGetFontInstance (
                     ATSUFontID iFont,
                     ItemCount iFontInstanceIndex,
                     ItemCount iMaximumVariations,
                     ATSUFontVariationAxis oAxes[],
                     ATSUFontVariationValue oValues[],
                     ItemCount *oActualVariationCount);

iFontID

A value of type ATSUFontID. Pass the ID of the font whose font instance you want information about.

iFontInstanceIndex

A 0-based index. Pass a value between 0 and one less than the count passed back in the function ATSUCountFontInstances.

iMaximumVariations

The maximum number of font variations. Typically, this is equivalent to the number of elements in the oAxes and oValues arrays. To determine this value, see the discussion below.

oAxes

An array of values of type ATSUFontVariationAxis. Before calling ATSUGetFontInstance, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, the array contains a list of the font variation axes in the font. You cannot pass NULL for this parameter.

oValues

An array of values of type ATSUFontVariationValue. Before calling ATSUGetFontInstance, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, the array contains a list of the font variation axes in the font. You cannot pass NULL for this parameter.

oActualVariationCount

A pointer to a count. On return, the actual number of font variations. This may be greater than the value passed in the iMaximumVariations parameter. You cannot pass NULL for this parameter.

function result

A result code. The result code kATSUInvalidFontErr indicates that the ID does not correspond to any installed font. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUGetFontInstance function obtains, for an indexed font instance, the corresponding axis and value.

The best way to use ATSUGetFontInstance is to call it twice:

Pass the ID of the font whose font instance you want information about in the iFont parameter, NULL for the oAxes and oValues parameters, and 0 for the other parameters. ATSUGetFontInstance returns the size of the oAxes and oValues arrays in the oActualVariationCount parameter.
Allocate enough space for an array of the returned size, then call the function again, passing pointers in the oAxes and oValues parameters; on return, the pointers reference the array of axes and values corresponding to the font instances in the font.

VERSION NOTES

Available beginning with ATSUI 1.0.